home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 22 / Cream of the Crop 22.iso / program / task3210.zip / TASK32.H < prev    next >
C/C++ Source or Header  |  1996-10-26  |  8KB  |  206 lines
  1. /***** TASK32.H *****/
  2. /*
  3.  * Version 1.00
  4.  * Header file for Tasker32 programs.
  5.  * All user documentation is contained herein.
  6.  */
  7.  
  8. /*
  9.  * COPYRIGHT AND DISCLAIMER:
  10.  * This file and associated files are Copyright (c) 1996 by Guy Thornley.
  11.  * Permission is granted for the end user to distribute all end programs that
  12.  * contain these routines and code as long as the copyright notice is not
  13.  * removed or changed in any way.
  14.  * This product is supplied without any express or implied warranty of any
  15.  * kind, that is, it is supplied "AS-IS". It is the end user's
  16.  * responsibilty to cover all support resulting from use or lask of use of
  17.  * this product.
  18.  */
  19.  
  20. /* #defines for readability and changeability */
  21. /* These come from the .ASM source. */
  22. #define TASK_NUM        10              /* Number of tasks          */
  23. #define TASK_MAX        (TASK_NUM-1)    /* Max task number          */
  24. #define TASK_UNUSED     0               /* Task is unused           */
  25. #define TASK_ACTIVE     1               /* Task is used and active  */
  26. #define TASK_CALLED     2               /* Task has been called     */
  27. #define TASK_PAUSED     4               /* Task is paused           */
  28. #define TASK_FAR        8               /* Task exits with far ret  */
  29. #define TASK_OK         0               /* Task is OK               */
  30. #define TASK_FAILED     1               /* Task is invalid          */
  31. #define TASK_NONE_FREE  65535           /* No free tasks            */
  32.  
  33. /* Typedefs for useful types */
  34. /* These should be used when interfacing to the tasker. */
  35. typedef unsigned short  ushort;
  36. typedef unsigned long   ulong;
  37. typedef unsigned int    uint;
  38.  
  39. /* The task entries */
  40. /* For accessing task records in memory. */
  41. #pragma -a1
  42. struct task_struct {
  43.   ulong   poff;
  44.   ushort  psel;
  45.   ulong   left;
  46.   ulong   delay;
  47.   ulong   freq;
  48.   ushort  status;
  49.   ushort  dssel;
  50. };
  51. #pragma -a.
  52.  
  53. /* External task information. */
  54. extern const struct task_struct tasks[TASK_NUM];
  55.  
  56. /* Prototypes */
  57. /* Declare the procs that the use can use. */
  58.  
  59. ushort task_init_tasker(void);
  60.   /* 
  61.    * Initializes the tasker. MUST be called before anything else.
  62.    * Paramaters:
  63.    *    None.
  64.    * Returns:
  65.    *    TASK_OK       For success. Tasker was initialized.
  66.    *    TASK_FAILED   Failure. Tasker cannot be used. Program should
  67.    *                  terminate with an error code. Possible causes of this
  68.    *                  are listed in notes.
  69.    * Notes:
  70.    *    - If it fails a possible cause is an incompatible DOS extender
  71.    *      running before the program starts up and Borland's DOS extender
  72.    *      in DPMI32VM.OVL is not used. In this case, the user should be told
  73.    *      to not use the offending memory manager or make a boot disk.
  74.    *    - This is compatible with Microsoft Windows 3.1x.
  75.    *    - If it fails the interrupt will not be hooked and all other Tasker32
  76.    *      routines may succeed but do nothing.
  77.    */
  78.  
  79. void task_set_timer_delay(ulong count);
  80.   /* 
  81.    * Sets the delay in the internal hardware timer channel 0 (master
  82.    * clock generator) to count.
  83.    * Paramaters:
  84.    *    count         This is the internal count to set the timer to. Only
  85.    *                  the low 16 bits are used. All others are ignored.
  86.    * Returns:
  87.    *    Nothing.
  88.    * Notes:
  89.    *    - The user should not call this directly but let Tasker32 control
  90.    *      the timer.
  91.    *    - Should the user update the timer speed make sure that the delay
  92.    *      is small enough so fast tasks will still function correctly.
  93.    */
  94.  
  95. ushort task_add(ushort f, void* p, ushort cs, ushort ds, ushort flg);
  96.   /* 
  97.    * Adds a task to the task queue to run at even intervals.
  98.    * Paramaters:
  99.    *    f             The frequency, in times per second, to call the
  100.    *                  passed routine.
  101.    *    p             The near offset to the function to call.
  102.    *    cs            The code selector of the function to allows far calls.
  103.    *    ds            The preferred data selector of the function.
  104.    *    flg           Aadditional flags or'd together about proc:
  105.    *                  TASK_PAUSED   Set to automatically pause proc.
  106.    *                  TASK_FAR      Set for a far call.
  107.    * Returns:
  108.    *    The task identification number. This should be saved so the caller
  109.    *    can update and control the task.
  110.    *    If TASK_NONE_FREE is returned there was no space left in the task
  111.    *    record structure to hold the task.
  112.    * Notes:
  113.    *    - For normal operation, on calling this the cs paramater should be
  114.    *      set to _CS, ds should be set to _DS and and flg should be set
  115.    *      to 0. Only change this if absolutly necessary and you are aware of
  116.    *      the results.
  117.    *    - TASK_NONE_FREE can be overcome by raising the TASK_NUM number in
  118.    *      the TASK32.ASM source file and reassembling and compiling.
  119.    */
  120.  
  121. ulong task_getdelay(ushort freq);
  122.   /*
  123.    * Computes the delay for a frequency that is appropriate for the system
  124.    * timer.
  125.    * Paramaters:
  126.    *    freq          The frequency, in timer per second, (Hz), to compute
  127.    *                  the delay for.
  128.    * Returns:
  129.    *    The appropriate delay in system timer ticks to achieve the given
  130.    *    frequency.
  131.    * Notes:
  132.    *    - Only the low 16 bits of the returned delay are used. However all
  133.    *      the others are set to 0 and should stay that way.
  134.    */
  135.  
  136. ushort task_delete(ushort taskid);
  137.   /*
  138.    * Deletes a task from the task queue. The task will no longer be called
  139.    * and the record is freed up for successive tasks to be added.
  140.    * Paramaters:
  141.    *    taskid        This is the ID number of the task that was returned
  142.    *                  from task_add().
  143.    * Returns:
  144.    *    TASK_OK       For success, task deleted OK.
  145.    *    TASK_FAILED   For failure, task was not deleted.
  146.    * Notes:
  147.    *    - Failure will mean that taskid was invalid.
  148.    */
  149.  
  150. ushort task_setstatus(ushort taskid, ushort status);
  151.   /*
  152.    * Sets given status bits of a task to control the tasking of the task.
  153.    * Paramaters:
  154.    *    taskid        The task ID number of the task to adjust.
  155.    *    status        The status bits the alter. These can be:
  156.    *                  TASK_PAUSED   To pause the task. The task will not be
  157.    *                                run until this bit is cleared. If the
  158.    *                                task currently has control the task will
  159.    *                                have to exit before this takes effect.
  160.    * Returns:
  161.    *    TASK_OK       For success, task status updated OK.
  162.    *    TASK_FAILED   For failure, task was not updated.
  163.    * Notes:
  164.    *    - Failure will mean that taskid was invalid.
  165.    */
  166.  
  167. ushort task_clearstatus(ushort taskid, ushort status);
  168.   /*
  169.    * Sets given status bits of a task to control the tasking of the task.
  170.    * Paramaters:
  171.    *    taskid        The task ID number of the task to adjust.
  172.    *    status        The status bits the alter. These can be:
  173.    *                  TASK_PAUSED   To unpause the task. The task will now be
  174.    *                                run if it was previously paused.
  175.    * Returns:
  176.    *    TASK_OK       For success, task status updated OK.
  177.    *    TASK_FAILED   For failure, task was not updated.
  178.    * Notes:
  179.    *    - Failure will mean that taskid was invalid.
  180.    */
  181.  
  182. void task_end_tasker(void);
  183.   /*
  184.    * Stops the tasker from running, restores interrupt vectors and resets
  185.    * the system timer to normal operation.
  186.    * Paramaters:
  187.    *    None.
  188.    * Returns:
  189.    *    Nothing.
  190.    * Notes:
  191.    *    - This *MUST* be called before ending the program or a system crash
  192.    *      will occur.
  193.    *    - It is suggested that this is installed with atexit() at startup
  194.    *      incase of premature program termination.
  195.    */
  196.  
  197. /*
  198.  * Syntax for task handlers:
  199.  *    void procname(const ushort tid);
  200.  * Where:
  201.  *    tid can either be ommitted or used. If used, it contains the ID number
  202.  *    of the task that caused it to be called.
  203.  *    No other paramaters are allowed.
  204.  */
  205.  
  206.